Introduce vllm_omni/metrics/definitions.py as the single source of
truth for metric family names, label sets, histogram buckets, and RTF
formulas. Server-side prometheus.py and bench-side MultiModalsBenchmark
Metrics now consume the same constants, eliminating the dual-track
naming drift between /metrics output and bench CLI reports.

Pre-work for the upcoming RFC extensions: per-modality audio/image/
video families (G1/G2), cross-stage transfer family (G3), and the
OmniPrometheusStatLogger wrap that relabels engine into stage+replica
(G7). All refactors are name-only; PR vllm-project#3362's existing 10 prometheus
tests pass unchanged.

Signed-off-by: LHXuuu <xulianhao.xlh@antgroup.com>

Phase 4 of multi-modal observability (RFC G3). Four Histogram families
with {model_name, from_stage, from_replica, to_stage, to_replica} labels,
emitted from the existing TransferEdgeStats accumulators in
OrchestratorAggregator:

  transfer_size_bytes          -- BYTES_BUCKETS, observed at TX hook
  transfer_tx_time_ms          -- MS_BUCKETS,    observed at TX hook
  transfer_rx_decode_time_ms   -- MS_BUCKETS,    observed at RX hook
  transfer_in_flight_time_ms   -- MS_BUCKETS,    observed at RX hook

Each .observe_*() corresponds to one physical transfer event (one chunk
hop) so the histogram tracks per-transfer distribution rather than
request-aggregated sums.

Two non-trivial design choices, both deviating from RFC §3.2.6:

1. Add model_name to the label set (RFC lists only the four stage/replica
   labels). Rationale: aligns transfer with the rest of the omni_*
   families (audio_*, image_*, video_*, num_requests_*) so PromQL joins
   on model_name work uniformly. Cardinality cost is zero for typical
   single-model deployments. To be amended back into the RFC as D11.

2. Resolve from_replica / to_replica by consulting the sticky-routing
   binding the orchestrator already maintains, rather than plumbing
   replica ids through TransferEdgeStats / StageRequestStats / connector
   adapters. Phase 2 (PR vllm-project#2396) gave us
   stage_pool.get_bound_replica_id(request_id), which returns the replica
   each request is bound to within a stage; we look it up at emit time.
   Five files would need touching otherwise (TransferEdgeStats,
   StageRequestStats, stage_pool.build_stage_metrics, adapter.on_forward
   call site, request bookkeeping). To be amended back into the RFC as D12.

Five edits:

1. definitions.py — TRANSFER_LABELS prepends model_name.

2. transfer.py — new OmniTransferMetrics(model_name) class with the four
   Histogram families and one observe method per family. Same wrapper
   pattern as OmniPrometheusMetrics (PR vllm-project#3362) and OmniModalityMetrics
   (Phase 3): bind model_name at __init__, accept stage/replica at
   observe time.

3. stats.py — OrchestratorAggregator gains two optional kwargs at
   __init__ (transfer_emitter, replica_resolver). record_transfer_tx
   and record_transfer_rx call thin _emit_transfer_tx / _emit_transfer_rx
   helpers after the existing accumulation, which fail-safe (skip emit)
   when either dep is missing or the resolver returns None for either
   side. The TransferEdgeStats accumulation path is unchanged so
   existing log/aggregation consumers stay intact.

4. omni_base.py — instantiate self.transfer_metrics alongside
   self.prom_metrics / self.mod_metrics.

5. async_omni.py — wire transfer_emitter and replica_resolver into the
   per-request OrchestratorMetrics construction. New
   _resolve_transfer_replica helper looks up
   self.engine.stage_pools[s].get_bound_replica_id(rid).

15 unit tests cover the 4-family registration, observe APIs, bucket
selection, multi-edge cardinality, plus the OrchestratorAggregator emit
hooks (tx + rx full emit, defensive skips for emitter=None /
resolver=None / one-side-resolves-to-None, rx skips stage 0). Stub
emitter records call signatures so the routing logic is asserted
without standing up a Prometheus registry.

Note: TX-side hook (record_transfer_tx) is emit-ready but
adapter.try_send_via_connector — its only caller — currently has no
upstream invocation in the main code path (likely plugin-driven or
about-to-land). RX side (record_transfer_rx) is the active path today;
TX side will start emitting as soon as the connector pipeline activates.

Signed-off-by: LHXuuu <xulianhao.xlh@antgroup.com>

…al{finished_reason}

Phase 5 of multi-modal observability (RFC G6). Collapse the two
PR-vllm-project#3362-era pipeline-level counters

  vllm:omni_num_requests_success
  vllm:omni_num_requests_fail

into a single per-reason Counter:

  vllm:omni_requests_success_total{model_name, finished_reason}

with finished_reason ∈ {stop, length, abort, ...} mirroring upstream
vllm:request_success_total. The previous "fail" path now maps to
finished_reason="abort" so the Pipeline-level success-rate dashboard
becomes one query (sum by (finished_reason) ...) instead of needing
two metrics joined.

Breaking change: dashboards / alerts that reference the old
num_requests_success / num_requests_fail counter names must migrate
to the new requests_success_total{finished_reason} family.

Four edits:

1. definitions.py — drop NUM_REQUESTS_SUCCESS, NUM_REQUESTS_FAIL.
   Add REQUESTS_SUCCESS (passed without _total since Counter
   auto-suffixes at exposition).

2. prometheus.py — replace _success_family + _fail_family with a
   single _completion_family using SUCCESS_LABELS = ("model_name",
   "finished_reason"). The label is bound per-call rather than at
   __init__ time.

   - OmniPrometheusMetrics.request_succeeded() gains a
     finished_reason="stop" default kwarg.
   - OmniPrometheusMetrics.request_failed() keeps its no-arg signature
     for back-compat with the cleanup call site, internally mapping
     to finished_reason="abort".

3. omni_base.py — at the request-finalize hook, extract
   finish_reason from engine_outputs.outputs[0].finish_reason
   (vLLM CompletionOutput convention) and pass it through to
   request_succeeded(). Falls back to "stop" when no completion
   output is present (defensive — e.g. diffusion stages).

4. tests/metrics/test_prometheus.py — refresh _PIPELINE_METRICS,
   exercise three reason buckets (stop x 2 + length x 1 + abort x 1)
   in the scrape fixture, replace the old success/fail-count assertions
   with per-reason ones, and adjust the histogram-count assertions
   (e2e/queue go from 2 to 3 since the abort path now only inc's the
   counter and doesn't observe latency).

Signed-off-by: LHXuuu <xulianhao.xlh@antgroup.com>

PR vllm-project#3362 introduced docs/usage/metrics.md and docs/design/metrics.md
covering its own pipeline-level + diffusion families. The follow-up
work in this branch (G1 audio, G2 image/video, G3 cross-stage transfer,
G6 success/fail merge into requests_success_total{finished_reason},
G7 OmniPrometheusStatLogger per-replica wrap) wasn't reflected. Refresh
both docs to the final state.

usage/metrics.md (+117 / -38):

- Request Tracking table swaps num_requests_success / num_requests_fail
  for the merged requests_success_total{finished_reason} family.
- New sections for Modality (audio / image / video) and Cross-Stage
  Transfer with the per-modality / per-edge metric tables.
- vLLM Engine Metrics section gains a before/after example showing how
  the G7 wrap reshapes engine -> stage + replica, with a note that the
  ~37 upstream families gain per-replica visibility automatically.
- Diffusion Engine Metrics section clarifies that omni-side diffusion
  families bypass the wrap (engine label = stage_id, not relabelled).
- Pipeline Type availability matrix gains modality / transfer /
  per-replica rows.
- Naming Convention section explains the RFC "co-position, different
  name" three-modality TTFP convention.

design/metrics.md (+260 / -74):

- Objectives section calls out the per-replica + modality + transfer
  goals introduced after PR vllm-project#3362.
- Architecture diagram replaces the original two-component picture with
  the four-component one (OmniPrometheusMetrics + OmniModalityMetrics +
  OmniTransferMetrics + OmniPrometheusStatLogger).
- Data Flow grows from two paths to four: Pipeline-level, Modality
  (finalize hook + audio_ttfp streaming hook), Cross-stage transfer
  (sticky-routing replica_resolver), and the wrapped per-engine path.
  The transfer subsection notes the TX-side hook is wired but currently
  inactive pending try_send_via_connector being called from the main
  code path.
- New "OmniPrometheusStatLogger Wrap (G7)" section explains the four
  upstream impedance points and the three coordinated mechanisms
  (class-level metric class slots, per_engine_labelvalues property
  descriptor, _RelabelMixin.labels() override) used to handle them.
  Also documents the stage_replica_map construction and the deferred
  dynamic add/remove decision.
- Metric Definitions table refreshed end-to-end: pipeline-level row
  now lists requests_success_total{finished_reason}; new modality and
  transfer subtables added; transfer subtable carries a note that
  model_name was added on top of the RFC-listed four
  stage/replica labels for cross-omni consistency.
- Logging vs. Prometheus section expanded to mention OmniModality /
  OmniTransfer alongside OmniPrometheusMetrics, and notes that
  OrchestratorAggregator.record_transfer_tx/rx fans out to both the
  log accumulator and the Prometheus emit hook in one method body.

Signed-off-by: LHXuuu <xulianhao.xlh@antgroup.com>